The 640 MEG Shareware Studio 2

home *** CD-ROM | disk | FTP | other *** search

/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / door / gapcdr.zip / GAPCDR.TXT < prev next >

Wrap

Text File | 1992-01-12 | 154KB | 5,167 lines

GAP Communications Online Software GAPCDR Door Interface Library Copyright (C) 1987-1992 by GAP Development Company. ALL RIGHTS RESERVED. No part of this manual shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from GAP Development Company. While every precaution has been taken in the preparation of this manual, GAP Development Company assumes no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein. GAPCDR is the sole and exclusive property of GAP Development Company. It is licensed and not sold to the end user with restrictions placed upon its use. GAPCDR is copyrighted by GAP Development Company. DESQview is a trademark of Quarterdeck. PCBoard is a trademark of Clark Development Corporation. WildCat! is copyrighted by Mustang Software. Contents Description 5 Major Features 5 Getting Started 7 Supported Compilers 8 Using GAPCDR 8 Points To Remember 10 Compiling And Linking 11 Using A Goto 12 BBS System Files 13 Sysop Setup And Functions 13 Configuration 14 Sysop Functions 15 Advanced Applications 16 Communications 16 DOS Window 18 Variables 20 Defines 20 Ansi Variables 20 DOOR.SYS Variables 21 Global Variables 23 Functions - Quick Reference 25 Functions - Detailed Reference 26 Index 79 Page 3 Page 4 GAP Communications GAPCDR Description Description GAPCDR is a professional development kit for Bulletin Board Door programmers. Written in Microsoft C version 6 and MASM version 6, it is fast, reliable, easy to use, and easy to incorporate into the serious programmer's source code. It consists of a set of C and assembler library routines to allow for easy door programming and interfacing. Borland C compatability is included. Major Features Major Features Interfaces with GAP Communications, PCBoard, WildCat, and other fine BBS programs that are capable of writing a DOOR.SYS file. Full communications support. Supports the FIFO buffers of the 16550 UART chip. Speeds up to 115,200 baud. Communications ports other than Com 1 and Com 2 possible. Supports CTS/RTS, automatically. Does not require watchdog or CTTY. Fully self contained, built in ANSI driver. Sysop sees what the caller sees. High speed text file display. Supports ANSI color and ASCII text files with no programming effort other than to make a single function call. Easy to use Random Number Generator. Informative Status Line display. Monitors keyboard activity and caller time remaining. Easy interface to BBS system. Page 5 GAP Communications GAPCDR Sysop chat with full word wrapping. Allows the sysop to shell to DOS. "Remembers" the default drive and directory which prevents file access errors. Credits caller with time spent chatting or while sysop is in a DOS shell. Sysop can twit caller without caller ever knowing the sysop is watching. Caller time can be increased or decreased. Full programmer control of whether or not to update the BBS system files. Time calculations are not dependent on the "seconds since midnight" and are thus unsusceptible to the midnight roll over. Timer routines are hardware independent. Automatic detection of multi-user system. Input routines are consistent throughout the program. Uses the latest in Microsoft C and MASM features. Extremely easy interfacing to door programs. Fully DESQView aware video routines as well as keyboard and COM input routines, and COM output routines. GAPCDR includes robust Communications routines which are fully interrupt driven. Written in highly optimized assembler, they are capable of operating at any speed which the UART on an IBM type of computer is capable of producing. The FIFO buffers in the 16550 UART are fully supported. CTS/RTS checking is automatic, and carrier detect is an integral part of each of the communications input and output routines. When there is a loss of carrier, a function in the main GAPCDR code will be called. This function defaults to shutting down the door and returning to the BBS, however you may modify it to do whatever you wish. Page 6 GAP Communications GAPCDR The built in ANSI driver makes GAPCDR a self contained unit. The driver is smart enough to know when a caller does not want ANSI sequences sent to his computer and it will filter out any such codes that pass through it. This allows you to create prompts with embedded ANSI sequences and display them without regard as to whether or not the caller has color "turned on". This also means you do not have to keep two sets of prompts (one with color attributes and one without). This is a great savings to you in precious DATA space. You may also use the ANSI driver to send color strings to the local monitor. Even if the caller is in mono mode, you may still send color strings and prompts to the ANSI driver and have them displayed in color on the local monitor. GAPCDR supports only the DOOR.SYS format for passing caller information to a door. We choose this format because of its universal acceptance and its inherent ability to remain stable. BBS programs frequently change and with those changes usually come modifications to the system files they create to interact with door programs. DOOR.SYS on the other hand was designed to include as much information about a caller as was thought necessary. Should new fields be needed to take care of new BBS features, it is a simple matter to add these new fields to the end of the file, thereby making the new version compatible with all prior versions. Most major BBS programs support DOOR.SYS. Getting Started Getting Started GAPCDR is distributed in archived format. The contents of the archive should be as follows: GAPCDR.TXT - Disk based documentation. GAPCDRS.LIB - Small model Library routines. GAPCDRL.LIB - Large model Library routines. GAPCDRBS.LIB - Small model Library routines for BC. GAPCDRBL.LIB - Large model Library routines for BC. GAPCDR.H - Door Interface include file. GAPSTRUC.H - Door Interface include file. CDOOR.ZIP - Sample program illustrating many of the features of GAPCDR. READ.ME - Any pertinent information which you should read. If you licensed the source code to GAPCDR you will receive most of the ASM, C, INC, H, BAT, and OBJ files that make up the GAPCDR Page 7 GAP Communications GAPCDR library. We include both Microsoft and Borland batch files to compile the source modules. Supported Compilers Supported Compilers We used the Microsoft C compiler version 6.0, the Borland C++ Compiler version 2.0, and MASM version 6. The linker and librarian were from their respective compilers. Since GAPCDR uses no floating point math, the C modules were compiled with the /FPa switch for Microsoft. This is the default for Borland, so no switches are necessary. For Microsoft C, in order to use the /FPa switch, you must tell the SETUP program that you want to create the Alternate Floating Point library. It will then create a set of libraries that make calls to the Alternate Math library instead of the Emulator Library. The difference in code size for a large model program that uses the Alternate library as opposed to the Emulator library is typically around 10k. Even if you do not use floating point arithmetic in your program, the Math Library will still be linked in because it contains the routines to do long arithmetic. So, the smaller the library, the smaller your programs! Place the GAPCDR files in your work directory. You may place the LIB files in the MSC\LIB or BORLAND\LIB directory. The text editor you use must allow control characters to be entered and displayed. The ANSI variables are initialized with literal characters and if your editor removes the ESC character from the strings, your ANSI displays will be quite messy. Using GAPCDR Using GAPCDR At the very beginning of your program, you must include the GAPCDR.H file. Without this file, nothing will work. It is normally included after the C header files that your program may need. To include the file, you type the following after including the regular C header files: #include "gapcdr.h" GAPCDR.H contains the declarations for the external global variables. In addition, it includes GAPSTRUC.H which contains the structure declarations and the function prototypes. Page 8 GAP Communications GAPCDR Note: Any of your source modules that include GAPCDR.H must have an include declaration for STDIO.H prior to including GAPCDR.H. It should be standard practice to include STDIO.H in your source modules anyway, so this shouldn't present any problems. The first thing that must be done prior to using any of the door functions, is to initialize GAPCDR itself. This is accomplished by making a call to read_cnf. Read_cnf opens the configuration file (the name of which you pass as a parameter on the door command line) and reads the first four lines of the file. If the configuration file cannot be found, the program will end. The format of the configuration file is as follows: c:\gap The Crow's Nest 0 0 The first line of the file is the path to the BBS default directory. The second line is the name of the BBS. The third line is the Port IRQ and the 4th line is the Port Base Address. If the sysop running your program has his BBS configured to use Com Ports other than 1 or 2, he would then enter the IRQ and Base address for his Com Port on lines 3 and 4. GAPCDR derives the Port Number from the DOOR.SYS file. The configuration file is usually given a name similar to the name of your door program, with a CNF extension. Read_cnf will leave this file open for your use. If you have any configuration options of your own, you may place them in this file beginning with line 5. Do not read your configuration options until after making a call to init_door (which should be the second function call in your program). Upon return from init_door, you are free to read your configuration options (if any). At this time, you should close the configuration file. Normally, your program is invoked with a command line parameter giving the name of the configuration file to use: DOOR DOOR.CNF You would use the argv parameter to your main function to extract the configuration parameter and then pass this parameter on to read_cnf. This allows the end user to use a single program (your Page 9 GAP Communications GAPCDR program) with multiple configuration files. This is especially important under multi-user systems where separate configuration files are needed. The configuration file is opened as a stream, so using fgets or any of the stream input functions would be appropriate for reading the data. Remember that the file pointer is passed back to you after the call to read_cnf. An example of the first few "door" statements that might appear in a source file would be: FILE *cnf_file; // pointer to config file cnf_file = read_cnf(argv[1]); // read the cnf file init_door(); // init the door fclose(cnf_file); // close the cnf file If there were no errors, read_cnf will return. You must now make a call to init_door. Init_door uses the information derived from line 1 of the configuration file to open and read DOOR.SYS. In addition, init_door opens the communications port (if a remote user is on), initializes some global variables, initializes the random number generator, initializes the ANSI driver, and installs a Ctrl-Break handler. If there is an error, init_door will not return. Instead it will end the program. That is basically all you have to do to initialize the GAPCDR module. When your program ends, you should clean house if necessary and call leave. Leave closes the communications port and any open files, restores the ISR routines to their original state, sends a sign off message to the caller, and then exits to DOS. It is of vital importance to exit the door by making a call to leave. Failure to do so will leave communication interrupts active and the ctrl-break intercept active. The vectors to these routines will be left in the interrupt vector table and the computer will surely lock up the first time any program is run. Points To Remember To get the ball rolling, include GAPCDR.H after the C header files. To initialize the door, call read_cnf with the name of your program's configuration file. Then call init_door. Call leave when your program is finished. Page 10 GAP Communications GAPCDR All input and output should be performed through the GAPCDR functions. The sample program gives good examples on how to accomplish this. If you use the C runtime output routines such as printf or cputs, the local screen will be a mess because the internal ANSI driver will not know where the cursor is. To determine if the BBS is a single or multi user system, check the variable called multi. If it is anything other than 0, then the BBS is multi-user and you should read/write your data files with sharing attributes. Do not use any of the BBS specific functions such as read_pcbsys or read_gapuser unless you know that your program is running with the appropriate BBS system. You may want to use a flag in your configuration file to determine which system your program is running with. These functions were provided to make your programming choores easier but using them basically restricts your door to the respective BBS system that the functions interact with. To test your program, you will need a DOOR.SYS file that was written for local exit. Of course, you can always modify any DOOR.SYS file and change the first line so that it reads COM0:. A complete set of sample files are provided for testing your program under local mode. Compiling And Linking Compiling And Linking GAPCDR has already been compiled with the necessary compile time switches for both Microsoft C and Borland C. To compile your programs, use whatever switches are required for your compiler. Microsoft C cl /c /FPa door.c link door,,NUL.MAP,+GAPCDRx Borland C bcc -c door.c tlink c0x+door,door.exe,NUL.MAP,+GAPCDRBx+Cx Page 11 GAP Communications GAPCDR Where door is the name of your program and 'x' is 'S' for the small model library or 'L' for the large model library. As was mentioned previously, GAPCDR was compiled with the /FPa option for Microsoft C. The /FPa option produces smaller executable files. If you licensed the source code to GAPCDR, there are suplementary files to aid in re-compiling and librarying the source modules. GAPCDR has not been tested with Quick C, although there is no reason why it should not work with the QC environment. GAPCDR uses the PASCAL function calling convention. If you are unfamiliar with this calling convention it means that the parameters to a function are pushed onto the stack from left to right instead of right to left. In addition, the function being called is responsible for removing arguments from the stack. In the C calling convention, the function making the call is responsible for restoring the stack. What this means is if you make 10 calls to show_mess, there will be 10 instances where the stack must be restored upon return from the function. In the PASCAL convention, there will be only one instance where this will occur and it will be in show_mess just prior to the actual return. The end result of using the PASCAL calling convention is smaller code size. It should be noted that the PASCAL convention cannot be used with functions that take a variable number of arguments. In addition, using the PASCAL convention absolutely requires that all functions be prototyped. Otherwise the compiler will generate redeclaration errors and the linker will generate unresolved external reference errors. Using A Goto Using A Goto A word about using goto. If you licensed the source code to GAPCDR, you will find that we use the goto in several places. It should be pointed out that speed and compactness, combined with readability, are our number one concerns. We performed several experiments with the goto. We took a very simple function that consisted of a while loop and a few statements embodied within the loop. We took the same function and rewrote it using a counter variable and a goto and removed the while loop. The assembler output and resultant object code was 1/2 the size as that of the function that used the while loop. Page 12 GAP Communications GAPCDR We are not proposing that anyone give up the fine structure of C and use gotos as a beginning programmer in Basic might do. In fact, if you are a beginning programmer in C, you should avoid using gotos altogether until you become more proficient. BBS System Files BBS System Files Since we are firm believers that the BBS system files belong to the BBS and should not be altered by any door program, updating the BBS system file is not automatic. If you wish that any decrease or increase in the user's time (kept track of in the timecredit variable), be made permanent, you may, after initializing the door, call the function that opens the system file. For PCB, this would be PCBOARD.SYS. Keep track of any time credits during the door programs operation, then call the function that updates the BBS system file. For GAP, you would need to re-write DOOR.SYS with any updated information. Sysop Setup And Functions Sysop Setup And Functions These sysop setup and function descriptions should be placed in the documentation of your door program. You should, of course, change the setup information to fit your particular needs. Door programs written with the GAPCDR Door Interface Module will run on any BBS system that is capable of writing a DOOR.SYS file. For GAP Communications and WildCat, you need do nothing special when configuring your doors. These programs will write a DOOR.SYS file automatically. For PCBoard, you must explicitly tell the Door File editor to write a DOOR.SYS file, when setting up a GAPCDR door program. Page 13 GAP Communications GAPCDR Configuration Configuration To configure the door for a particular BBS setup, a configuration file must be used. At the very minimum, this file will contain four lines. It may contain more than four depending upon a particular door's configuration requirements. The name of the file is usually the same as that of the door program but with a CNF extension. The minimum requirements for the file are as follows: c:\gap The Crow's Nest BBS IRQ Port Address The first line is the full path to your BBS default directory. For GAP, this is usually C:\GAP. For PCB, this is usually C:\PCB. The second line is the name of your BBS. The third line is the IRQ that should be used for the port, and the fourth line is the Base Port Address. If you are just using Com 1 and Com 2, you may enter a 0 on these two lines. GAPCDR will obtain the sysop's name from the DOOR.SYS file. You must now create a batch file to invoke the door. This batch file is placed in the directory where you told your BBS SetUp program to look for it. Such a batch file might look like this: @echo off cd \gap\doors\tourist tourist tourist.cnf cd \gap As you can see, the door is invoked by passing the configuration file name as the first parameter. You will also need to modify your doors menu files and the data file that tells the BBS what your doors are and the security level needed to access them. For GAP, these are respectively: DOORM DOORMG DOORS.DAT Page 14 GAP Communications GAPCDR If you are running multi-nodes, simply create a separate door configuration file for each node, and number them. For instance, for a 3 node system, you might have the following configuration files: TOURIST1.CNF TOURIST2.CNF TOURIST3.CNF The only difference between the three would be the 1st line which points to the default directory for the particular node. Multi-user operation is automatic.The DOOR.SYS file contains a field that specifies if the BBS is multi-user or not. Sysop Functions Sysop Functions The following sysop functions are available while awaiting keyboard input : F5 - Shell to DOS. F8 - Twit user and return to BBS. F10 - Initiate chat with user. CF10 - Answer user page bell. Home - Main user stats. End - Displays sysop keys available. PgDn - Secondary user stats. Up Arrow - Increase user's time remaining. Dn Arrow - Decrease user's time remaining. One of the nicer features about using the TWIT key, is the user is not told that "the sysop wants them to return to the BBS". Instead, a very plain and simple message of "returning you to the BBS" is displayed. This way, the user is given no indication that the sysop is hovering about. When using the F5 shell to DOS key, to return to the door program, simply type EXIT at the DOS command prompt. It is not necessary to change directories back to the door directory. GAPCDR is smart enough to know which drive and directory the door program is in and will reset the defaults upon return from DOS. In addition, the status line will remain on the screen. It should be noted that when in a DOS shell, the GAPCDR status line is protected by intercepting BIOS video calls. If you use ANSI.SYS replacements which write directly to the video, you will Page 15 GAP Communications GAPCDR not have this protection and your status line will scroll off the screen The Up and Down Arrow keys increase and decrease the user's time respectively by 5 minutes for each press of the key. There is no indication of what is occurring (except by the fact the user's time remaining will change), so the sysop should try not to have a lead finger. The increase or decrease is effective only while the user is in the door. Whether or not these time credits (plus or minus) are made a permanent part of the user record so that upon return from the DOOR, the BBS program will recognize them, depends upon the door author. Advanced Applications Advanced Applications GAPCDR includes a great many advanced functions which can be used with or without the BBS Door Interface (i.e., automatic status line, time left checking, keyboard timeout checking, etc). Communications Communications The communications functions are an integral part of GAPCDR and are called automatically by an output routine if the variable local is set to 0. However, they may be used stand alone or called directly if necessary. These routines are fully self- contained with the exception of 3 global variables and 3 external functions. The global variables are: baud - Port speed gotdv - Flag signalling the presense of DESQview port - Communications Port Number The external functions are: no_carrier - Called if carrier is dropped timer - Time delay routine dv_pause - Called to give up time slice Before using the communications routines as stand alone functions, you should make a call to dv_here so that it can set Page 16 GAP Communications GAPCDR the gotdv flag. If you are not concerned about the presense of DESQview, you must declare this variable and initialize it to 0: short near gotdv = 0; Note that it must be declared such that it resides in the default data segment. If you declare the variable yourself, you must insure that the DESQVIEW.ASM module is not linked in to your program. You will need to create a dummy function called dv_pause that does nothing but return. This is necessary because even if you do not wish to use the dv_pause function, the linker will complain if it cannot find it: void _pascal dv_pause(void); Next, you must set the variable port to the port number you will be using. Ports start at 0, where COM 1 equals Port 0. Then set the variable baud to the bps rate you want the port opened at. Your program will need to include a function called no_carrier. It is prototyped as: void _pascal no_carrier(void); This function is called by the communications routines when they detect that there is no carrier. You may do whatever you wish inside this function but keep in mind that it will continue to be called if there is no carrier on the port. You most certainly do not want to make calls to any of the communications functions from inside this routine or a stack overflow will eventually result. If you wish to do your own carrier detecting (as you would if you were going to be using these functions to create a dial out type of program), then this function can simply contain a return. Once you have the global variables configured, the first step in initializing the serial port is to make a call to setport. Setport creates the receive buffer and then sets up the serial port. After the port is configured, you should then call init_port to set the baud, parity, and data bits. Init_port supports all the baud rates that a UART on an IBM type of computer is capable of utilizing. After this the port is fully configured and may now be utilized. Before your program ends, you must call reset_port to restore the interrupt vector back the way it was. Page 17 GAP Communications GAPCDR The main input routines are: comgetc - Get a single character from the port comgetd - Get a character with timeout The main output routines are: computc - Send a single character computs - Send a string There are routines for checking carrier, turning DTR on and off, checking if there are any characters in the receive buffer, and clearing the receive buffer. If you need to change baud rates simple set the variable baud to whatever bps rate you want to change to and then call init_port. DOS Window DOS Window GAPCDR includes some very advanced functions for setting up what we call a DOS Window. This is a Window that you define on the local screen and to which all DOS output will be redirected. For instance, if you needed to shell to DOS to run PKUNZIP or DSZ, you could set up a DOS Window and all output from these two programs will be contained inside the window. The window can also be used without shelling to DOS although there is really no practical use for doing so. To set up a DOS window, the first thing you should do is make a call to get_attr so that the current screen colors can be stored away. This is necessary because you may want to use special colors in your DOS window. By storing the original screen attributes, they can be restored when you close the window, thereby keeping the user's screen colors the way the user likes them! At the beginning of your program call get_attr. Do this before you do any screen output. You will then make several calls to the various GAPCDR functions to setup your DOS window. Once it is configured, you can then shell to DOS and do whatever you like. All screen output will take place inside the window. Please note that if you use a console driver other than CON or ANSI.SYS (and this generally includes all so called video speed up programs), or run a program that writes directly to the screen, then output will not take place inside of the window. This is because video Page 18 GAP Communications GAPCDR speed up programs generally write directly to the screen instead of using the BIOS. To see how the DOS window works, after setting it up, issue the following call: system("COMMAND"); This will put you in a DOS shell. You may then execute various DOS functions and get a feel for what it looks like. Be sure to type "exit" to return to your program. When you no longer need the DOS window, it is imperitive that you remove the interrupt 10 (BIOS) intercepter or your computer will hang when you exit the program. There is a fully working example of a DOS Window in the CDOOR example program. It shows how to save a portion of the screen, draw a box, set up the interrupt 10 intercepter and shell to DOS. Upon return from the shell, it will remove the DOS Window. Page 19 GAP Communications GAPCDR Variables Variables Defines Defines The following defines are used when calling show_mess. NO - Defined as 0 YES - Defined as 1 Ansi Variables Ansi Variables ANSI strings contain the actual ANSI color sequences. A_BLACK - ANSI codes for Black A_BLUE - ANSI codes for Blue A_BROWN - ANSI codes for Brown A_CYAN - ANSI codes for Cyan A_GREEN - ANSI codes for Green A_MAGENTA - ANSI codes for Magenta A_RED - ANSI codes for Red A_WHITE - ANSI codes for White A_BBLACK - ANSI codes for Grey A_BBLUE - ANSI codes for bright Blue A_BCYAN - ANSI codes for bright Cyan A_BGREEN - ANSI codes for bright Green A_BMAGENTA - ANSI codes for bright Magenta A_BRED - ANSI codes for bright Red A_BWHITE - ANSI codes for bright White A_YELLOW - ANSI codes for Yellow Page 20 GAP Communications GAPCDR DOOR.SYS Variables DOOR.SYS Variables DOOR.SYS variables are initialized while reading the DOOR.SYS file. These variables are the door programmer's connection to the BBS. Short Integers Short Integers alarm - 0 = caller alarm off, 1 = on baud - DTE bps rate (unsigned) bell - 0 = page bell off, 1 = bell on color - 0 = no color, 1 = color curfiles - current files downloaded dflt_color - BBS default color expert - 0 = novice, 1 = expert level - user's security level local - 0 = remote user, 1 = local user maxfiles - max files available minsleft - minutes left at door start multi - 1 = system is multi-user node - node number in use, 0 = single page - page length parity - actually data bits, not used port - com port being used printer - 0 = printer off, 1 = printer on realcredit - time credits from the BBS screen - 0 = screen off, 1 = screen on userbaud - remote user's bps rate (unsigned) Page 21 GAP Communications GAPCDR Long Integers Long Integers curbytes - current download bytes doors_open - total doors opened downbytes - total download bytes downloads - total number of downloads maxbytes - max bytes can download mesleft - total messages left recnum - user's record number timeson - # of times on upbytes - total upload bytes uploads - total number of uploads Character Arrays Character Arrays bphone - user's business phone number city - user's home town event_time - event run time fname - user's first name handle - caller's Handle hphone - user's home phone number last_new - last new files scan lastdate - last date user was on lname - user's last name password - user's password subscrip - date user's subscription expires username - user's full name Page 22 GAP Communications GAPCDR Global Variables Global Variables These variables are the documented, global variables (initialized and used by GAPCDR). They may be modified and/or used at the programmer's discretion. Characters Characters chat - true if chatting with user clockon - 0 no clock, 1 display clock column - column we are at now endview - true if dont want to viewany more flag - flag that a space was pressed instatus - if doing status line noup - if 1, dont uppercase characters NS - true if in Non Stop mode redisplay - true if wants to start over usemore1 - true if showing a file view - true to use the more prompt wordwrap - column to wrap words at Short Integers Short Integers base_add - base address for port irq - IRQ for port lines - # of lines currently displayed normal - current display color timecredit - any time credits user may have timeleft - time user has left Long Integers Long Integers starttime - time door opened temptime - for calculating time out timenow - current time Page 23 GAP Communications GAPCDR Character Arrays Character Arrays anystring - global garbage collector bbs_dir - path to DOOR.SYS birthday - caller's birth date board_name - name of the BBS BS - backspace characters CRLF - carriage return/line feed characters curtime - holds the current time as a string gendir - path to the BBS gen dir maindir - path to the BBS main dir strtime - holds the time string sysname - sysop's name Structures Structures GAP_USER user - GAP's User Record PCBSYS pcbsys - PCB's System Record PCBUSER pcbuser - PCB's User Record These structures are fully commented in the GAPCDR.H header file. Note that when utilizing the GAP user structure, all string fields are fully padded with spaces and the last position must be a 0. Page 24 GAP Communications GAPCDR Functions - Quick Reference Functions - Quick Reference access1 - Checks for the existence of a file. ansi - Displays ANSI color strings. backspace - Sends one or more backspaces. ckeypress - Checks for a remote or local key press. clear_scrn - Clears the local and remote screens. clr_buf - Cleare the communications receive buffer. cls - Clears the 1st 23 lines on the local screen. cls_all - Clears the entire local screen. comgetc - Gets a character from com port. comgetd - Geta a character from com port with timeout. computb - Sends a buffer of data to com port. computc - Sends a character to com port. computs - Sends a string to com port. cursoff - Turns local cursor off. curson - Turns local cursor on. do_chat - To allow sysop to chat with remote user. dtr - Toggels the DTR line on or off. dv_here - Checks for the presense of DESQView. dv_pause - Gives up remainder of time slice to DV. elap_time - Computes elapsed time. empty - Empties a string. fix_color - Modifies ANSI driver for color or mono. gapputc - Sends a character to local and remote. gapputs - Sends a string to local and remote screens. getakey - Gets one key responses. getkeyc - Gets keyboard character and scan code. get_attr - Gets startup video attribute. get_random - Returns a random number. get_string - Gets a string of characters. init_ansi - Initializes ANSI driver. init_com - Initializes Communications Port. init_door - Initializes the Door. init_port - Sets up Communications Port. iscd - Checks if there is a Carrier. leave - Shuts down door and returns to the BBS. lputc - Sends a character to local screen. lputs - Sends a string to local screen. make_sound - Makes noise on local computer. more - Checks for a full screen. nl - Sends a CR/LF to local and remote. no_carrier - Called by the Comm Routines if Carrier lost. pagesysop - Alerts sysop that the user wants to chat. pause - Sends a "Press [Any Key] To Continue" prompt. putkey - Used by chat for word wrapping. read_cnf - Reads the door configuration file. Page 25 GAP Communications GAPCDR read_doorsys - Reads DOOR.SYS. read_gapuser - Reads USERS.DAT. read_pcbsys - Reads PCBOARD.SYS. read_pcbuser - Reads PCB USERS file. read_score - Reads and displays top 10 scores. reset_port - Restores Communications Port. restore_screen - Restores a portion of the screen. rest_cbreak - Restores Ctrl-Break vector. rest_int10 - Restores BIOS vector. rts - Toggels RTS line on or off. rxempty - Checks if any characters in receive buffer. save_screen - Saves a portion of the screen. setport - Initializes Communications port. set_attr - Sets video attributes. set_cbreak - Initializes Ctrl-Break vector. set_cord - Sets up a DOS Window. set_int10 - Initializes BIOS trapper. set_status - Displays status line. show_file - Displays text files. show_mess - Displays a message. timer - Time Delay. time_credit - Gives credits for time used. time_left - Computes time remaining. trim - Trims spaces from string. update_clock - Updates status line clock. wrap_word - Wraps a word. write_gapuser - Writes USERS.DAT. write_pcbsys - Writes PCBOARD.SYS. write_pcbuser - Writes PCB USERS. write_score - Creates and maintains top 10 scores file. Functions - Detailed Reference Functions - Detailed Reference Functions will return either a void (nothing), a short value, or a character pointer. The function descriptions will note whether or not a function is high level or low level. The high level functions are basically the only functions you will ever need to use. When necessary, they will call other functions to carry out their work. The low level functions, on the other hand, are more single purpose, and they generally require calls to other low level functions to perform the same task as one call to a high level function. Page 26 GAP Communications GAPCDR access1 ----------------------------------------------------------------- Purpose Checks for the existence of a file. short access1(char *filename); filename Full path and name of file Type High Level Description This function is used to check for the existence of a file. It works in a multi-user environment and is not affected by file sharing attributes. Return Value 0 = File exists, 1 = File not found. Example if ((access1("FILE.DAT"))) show_mess("Sorry, File does not Exist!", YES,YES); ansi ----------------------------------------------------------------- Purpose Displays ANSI color sequences. void ansi(char *color); color Ansi color string Type High Level Description This function will send a string of ANSI escape sequences to the remote user and to the local console. The ANSI codes for the various colors are declared as global variables. If the remote or local user is in non graphics mode, the function returns immediately. Return Value None. Example ansi(A_BWHITE); // Change color to bright white Page 27 GAP Communications GAPCDR backspace ----------------------------------------------------------------- Purpose Sends one or more backspaces. void backspace(short num); num Number of backspaces to send Type High Level Description In order to actually erase a character on the screen, you must send a 3 character sequence which consists of backspace, space, backspace. This function will send as many of these 3 character sequences as you specify in the parameter list. Return Value None. Example backspace(1); // erase last character sent ckeypress ----------------------------------------------------------------- Purpose Checks for a remote or local key press. short ckeypress(void); Type High Level Description This function will check the local keyboard as well as the communications receive buffer to see if a key is waiting to be read. It is most often used in loops that monitor keyboard timeout, time remaining, etc. Return Value 0 = no key is waiting, 1 = a key is waiting. Example c = ckeypress(); // key pressed? while(!ckeypress()) // do nothing { // until a key is pressed dv_pause() // give up time slice } Page 28 GAP Communications GAPCDR clear_scrn ----------------------------------------------------------------- Purpose Clears local and remote screens. void clear_scrn(void); Type High Level Description This routine will use the assembler routine cls to clear the first 23 lines of the local screen. If the remote caller is in non-color mode, it sends a CTRL-L to the remote screen, otherwise it sends the ANSI clear screen sequence. Return Value None. Example clear_scrn(); // clear screen clr_buf ----------------------------------------------------------------- Purpose Clears the Communications receive buffer. void clr_buf(void); Type Low Level Description Empties the receive buffer such that any pending characters are simply ignored. Return Value None. Example clr_buf(); // clear the receive buffer Page 29 GAP Communications GAPCDR cls ----------------------------------------------------------------- Purpose Clears the first 23 lines on the local screen. void cls(void); Type Low Level Description This function will clear the first 23 lines on the local screen, thereby protecting the bottom 2 lines. Return Value None. Example cls(); // clear 1st 23 lines cls_all ----------------------------------------------------------------- Purpose Clears the entire local screen. void cls_all(void); Type Low Level Description This function will clear the entire local screen. It is used by leave to tidy up the screen. Return Value None. Example cls_all(); // clear entire screen Page 30 GAP Communications GAPCDR comgetc ----------------------------------------------------------------- Purpose Retrieve a character from communications buffer. short comgetc(void); Type Low Level Description Checks the communications receive buffer and returns the next character, if any. Return Value Next character in buffer or -1 for no characters to read. Example c = comgetc(); // get a character from remote comgetd ----------------------------------------------------------------- Purpose Retrieve a character from comminications buffer with delay. short comgetd(short secs); secs Number of seconds to wait Type Low level Description This function is the same as comgetc, except that if there are no characters in the receive buffer, it will wait for the number of seconds you specify. Comgetd is fully DESQview aware and will give up the program's time slice while waiting for incoming characters. Return Value Next character in buffer or -10 for time-out (no characters to read). Example if ( (comgetd(2)) == -10) // wait for 2 seconds ; // nothing happening Page 31 GAP Communications GAPCDR computb ----------------------------------------------------------------- Purpose Sends a buffer of data out the communications port. void computb(char *buffer,short len); buffer Buffer containing data to send len Number of bytes to send Type Low Level Descripton This function will send a user suplied buffer of len bytes out the communications port, one byte at a time. It will not return until all characters have been sent. Return Value None. Example computb(buffer,100); // Send 100 bytes of data computc ----------------------------------------------------------------- Purpose Sends a single character out the communications port. void computc(unsigned char ch); ch Character to send Type Low Level Description Will send a single character out the communications port. Return Value None. Example computc('A'); // Send a character Page 32 GAP Communications GAPCDR computs ----------------------------------------------------------------- Purpose Sends a string of characters out the communications port. void computs(char *str); str String to send Type Low Level Description Will send a string of characters out the communications port. Note that unlike computb, the number of bytes to send is determined by the length of the string. Therefore this function stops sending characters when it encounters the null byte. Return Value None. Example computs("Send this string"); // send a string cursoff ----------------------------------------------------------------- Purpose Turns the local cursor off. void cursoff(void); Type Low Level Description This function is used to turn the cursor on the local monitor off. Return Value None. Example cursoff(); // turn the cursor off Page 33 GAP Communications GAPCDR curson ----------------------------------------------------------------- Purpose Turns the local cursor on. void curson(void); Type Low Level Description This function is used to turn the cursor on the local monitor on. Return Value None. Example curson(); // turn the cursor on Page 34 GAP Communications GAPCDR do_chat ----------------------------------------------------------------- Purpose To allow sysop to chat with remote user. void do_chat(void); Type High Level Description This function allows a one on one chat with a re- mote user. If the caller is in graphics mode, the sysop's key presses will be displayed in green and the remote user's key presses will be displayed in white. Text will automatically wrap at column 76. To exit chat, press either the ESC key or type a CTRL-X. Note that the user may also send these characters to end chat. The user will receive full credit for the time spent chatting with the sysop. However, this function will not update the BBS system file so it is possible that the user may be logged off (with an out of time message) when he/she returns to the BBS. Return Value None. Example do_chat(); // chat with caller empty(response,1); // initialize string get_string(response); // get a string if (response[0] == 'P') // paging sysop do_chat(); // chat with sysop Page 35 GAP Communications GAPCDR dtr ----------------------------------------------------------------- Purpose Toggle the DTR line on and off. void dtr(short how) how 0 = Turn DTR off. 1 = Turn DTR on Type Low Level Description This routine is used to turn the DTR line of the communications port on or off. Turning DTR off while there is a carrier will cause the modem to drop carrier on the remote caller. In order to send commands to the modem, DTR needs to be on. Return Value None. Example dtr(1); // turn DTR on computs("ATZ"); // reset the modem Page 36 GAP Communications GAPCDR dv_here ----------------------------------------------------------------- Purpose Checks to see if the program is running under DESQview. short dv_here(void); Type Low Level Description This function should generally be called when a program first starts (before any screen output is performed). It makes a special DOS call to see if DESQview is installed. If so, it sets an internal flag indicating the presense of DV. If the program is detected to be running under DESQview then all "do nothing" loops (those loops that are looking for something to do but because they are waiting for keyboard or com input, are basically taking up computer time doing nothing), will give up the remainder of their time slice after they figure out there is nothing for them to do. In addition, because the built in ANSI driver writes directly to the screen, if DESQview is present, the driver will instead write to DV's video shadow buffer. This function is automatically called by init_door so it is not necessary to call it again. Return Value DESQview version number or 0 for not installed. Example if ( (dv_here())) show_mess("We are running under DESQview!", NO,YES); Page 37 GAP Communications GAPCDR dv_pause ----------------------------------------------------------------- Purpose Give up remainder of time slice to DESQview. void dv_pause(void); Type Low Level Description If DESQview is installed, this function will make a call to DV such that DV will immediately switch to another task. Note that dv_here must be called at the beginning of the program since it sets an internal variable that this function checks to see if DESQview is running. You should use this function inside of all "do nothing" loops. Return Value None. Example time (&temptime); // start timer while (!getakey()) // until a key is pressed { elap_time(); // check time remaining dv_pause(); // give up time slice } Page 38 GAP Communications GAPCDR elap_time ----------------------------------------------------------------- Purpose Computes elapsed time while waiting for keyboard input. void elap_time(void); Type High Level Description This function is used in loops that await a key- board response. Prior to entering the loop, the variable called temptime should be initialized with the current time. Once inside the loop, this function should be called to keep track of the elapsed time. If there is no keyboard response within 4 minutes, the user will be logged off. Return Value None. Example time (&temptime); // start timer while (!getakey()) // until a key is pressed { elap_time(); // check time remaining dv_pause(); // give up time slice } Page 39 GAP Communications GAPCDR empty ----------------------------------------------------------------- Purpose Empties a string to all spaces. void empty(char *str,short len); str The string to be emptied len Number of bytes to clear Type High Level Description Before using the string input routine, get_string, the string must first be cleared to the maximum number of bytes allowed to be input. Empty clears the string to all spaces and adds a null byte at the end. The null byte is not counted in the len parameter. Return Value None. Example char instr [11]; empty(instr,10); // empty the string get_string(instr); // get up to 10 characters // of input Page 40 GAP Communications GAPCDR fix_color ----------------------------------------------------------------- Purpose Modify ANSI driver according to user's color. void fix_color(void); Type Low Level Description The ANSI driver is self modifying, meaning that depending upon the color preference of the user, it will adjusts its code accordingly. This function is called by init_ansi and should never need to be called by the programmer directly unless the programmer provides a menu choice whereby a caller may toggle his/her color mode on and off. In such a case, you would immediately need to call fix_color so that the ANSI driver can adjusts itself. The caller's color preference is stored in the variable color where 0 means no color, and 1 means color. Return Value None. Example show_mess("Toggle Color",NO,NO); // part of menu empty(response,1); // clear string get_string(response); // get response to menu if (response[0] == 'C') // wants to toggle color { if (color) color = 0 else color = 1; fix_color(); // fix up ANSI driver } Page 41 GAP Communications GAPCDR gapputc ----------------------------------------------------------------- Purpose Sends a single character to local and remote. void gapputc(short ch); ch Character to send Type Low Level Description This is one of the main output routines that is used internally by GAPCDR. It is part of the ANSI driver. It will send a single character to the local screen and if a remote caller is on, will send the character to the communications port as well. Return Value None. Example gapputc('A'); // display a character while ( (c = getakey()) == 0) // wait for keypress dv_pause(); // give up time slice gapputc(c); // display character Page 42 GAP Communications GAPCDR gapputs ----------------------------------------------------------------- Purpose Sends a string of characters to local and remote. void gapputs(char *str); str String to send Type Low Level Description This is one of the main output routines that is used internally by GAPCDR. It is part of the ANSI driver. It will send a string of characters to the local screen and if a remote caller is on, will send the string to the communications port as well. If a caller is in mono mode, the ANSI driver will strip any ANSI sequences from the string. This allows you to "colorize" your strings with ANSI codes and not have to worry if the caller has his color setting turned on. This routine is much faster than show_mess (in fact, this is the function that show_mess calls), but it does not provide for ringing the bell or automatically sending a carriage return and line feed after the string. You can however embed these characters into the string. It is suggested that you not embed the bell character into the string since the sysop may have the alarm toggled off and may not appreciate the computer making noise when he/she doesn't want it to. Return Value None. Example gapputs("This is a string of characters"); // this example embeds the CR/LF pair at the beginning // and end of the string gapputs("\r\nThis is a string\r\n"); Page 43 GAP Communications GAPCDR getakey ----------------------------------------------------------------- Purpose Gets one key responses short getakey(void); Type High Level Description This is the main keyboard input routine. It is called by get_string as well as any keyboard polling loops. It checks the receive buffer as well as the local keyboard for a key press. If one is not found it returns 0. The character input is not echoed. Since 99% of all keyboard input comes from this routine, it checks for time remaining, keyboard time-out, as well as special sysop function keys. The timeleft variable is updated by this routine. This is the variable you would normally use in a prompt such as: [20 mins left] Main Command : Return Value ASCII code for the key pressed or 0. Example c = getakey(); // get a character Page 44 GAP Communications GAPCDR getkeyc ----------------------------------------------------------------- Purpose Gets keyboard character and scan code. short getkeyc(void); Type Low Level Description This is the main keyboard input routine which is called internally by getakey. It returns the keyboard character or if the key struck was an extended key, it will return a unique code. These codes are defined in GAPSTRUC.H as F1, Home, etc. This function always waits for a keypress so it should not be called unless you know there is a key waiting. Return Value ASCII code for the key pressed or a unique code for extended keys. Example keyc = getkeyc(); // get a keyboard character get_attr ----------------------------------------------------------------- Purpose Retrieves the current screen color. void get_attr(void); Type Low Level Description This function is used at the very start of a program to "remember" the screen color. It stores the color in a special location so that the screen attributes can be restored by the DOS Window routines. You do not need to call this routine if you have no plans to use the DOS Window. Return Value None. Attribute is stored in an internal location. Example get_attr(); // Remember screen attributes Page 45 GAP Communications GAPCDR get_random ----------------------------------------------------------------- Purpose Gets a random number. short get_random(short low,short high); low Lowest number acceptible high Highest number acceptible Type High Level Description This routine is provided because it is much easier to use and understand than the C library routine (which drags in the floating point library). Provide as parameters, two integers. The first parameter is the lowest number you will accept as a random number, and the second parameter is the highest random number you will accept. The function will return a random integer between the range specified (low and high are included in the range of numbers). It is not necessary to seed the random number generator as this is done automatically for you during program initialization. Return Value A random number between range specified. Example rndnum = get_random(1,10); // get a random num Page 46 GAP Communications GAPCDR get_string ----------------------------------------------------------------- Purpose Gets a string of characters. void get_string(char *string); string Storage for input characters Type High Level Description This is the main input routine. It will get a string from either the remote user or the local keyboard. The string passed will be set to the characters received. The length of the input string is determined by the length of the string passed. Before calling, you must initialize the passed string with spaces. The number of spaces in the string determines the number of characters allowed to be input. If a user attempts to type more characters than allowed, the cursor will not move pass the end of the string. Input ends when the Enter key is pressed. To initialize the string, use the empty function. WARNING : It is extremely important that the passed string be initialized. Failure to set the string to spaces, will cause unpredictable results! This function does not return a new string con- taining the keyboard input. Instead, it modifies the string you pass to it in the parameter list. The string will be stripped of any trailing spaces. Get_string automatically uppercases the string. If you wish to disable this feature, set the variable noup to 1 just prior to calling the function, and then set it back to 0 when the function returns. Get_string will automatically check for keyboard activity so it is not necessary for you to do so. Return Value None Example get_string(instr); // get a string Page 47 GAP Communications GAPCDR char instr [20]; // First initialize the string. In this case we will // accept up to 10 characters empty(instr,10); // initialize string get_string(instr); // get string init_ansi ----------------------------------------------------------------- Purpose Initialize ANSI driver. void init_ansi(void); Type Low Level Description This routine is called by init_door so it is not necessary for you to call it again. It sets up the ANSI driver so that it knows the sysop's default color, the current cursor position, etc. Return Value None. Example init_ansi(); // Initialize ANSI driver init_com ----------------------------------------------------------------- Purpose To configure the communications port. void init_com(void); Type High Level Description This function takes the information provided by DOOR.SYS and makes a call to setport to set up the communications port and receive buffer. It is called internally by init_door. If there is an error setting up the port, init_com will exit the program. Return Value None. Exits on Error. Example init_com(); // Initialize com port Page 48 GAP Communications GAPCDR init_door ----------------------------------------------------------------- Purpose Initializes the GAPCDR functions. void init_door(void); Type High Level Description This routine must be called immediately after calling read_cnf. It initializes the door, opens and reads system files, initializes the com port, initializes global variables and in general, makes sure that all of the files required for operation are present. If an error occurs while trying to initialize, the function will display an error message and end the program. Return Value None. Exits on error. Example fp = read_cnf("DOOR.CNF"); // read cnf file init_door(); // init the door fclose(fp); // close configuration file init_port ----------------------------------------------------------------- Purpose Initialize port to baud, data, and parity. init_port(short parity, short data); parity 0 = None, 1 = Even data 6,7,or 8 data bits Type Low Level Description Sets the communications port to the parity and data bits passed as parameters. The baud rate is contained in a global variabled called baud. The port number (where COM 1 equals port 0) is contained in a global variabled called port. RETURN VALUE 0 = SUCCESSFUL, 1 = ERROR. Example init_port(0,8) // Initialize to N,8,1 Page 49 GAP Communications GAPCDR iscd ----------------------------------------------------------------- Purpose Check for Carrier on the Communications Port. short iscd(void); Type Low Level Description This function allows you to test the communications port for a remote carrier signal. Note that carrier checking is performed automatically by the communications routines so it is not necessary for you to explicitly check for carrier unless you have a need to override the default actions taken. Return Value Returns 0 if there is no carrier and 1 if there is a carrier. Example if ( !iscd()) // is there a carrier? leave(99); // nope, lets quit leave ----------------------------------------------------------------- Purpose Exits the program. void leave(short code); code Exit code to terminate with Type High Level Description When the program terminates, it must call this function to end. This is the only proper exit from the door. It is of vital importance to end your program through this function so that the interrupt service routines that are installed at door beginning can be removed. Return Value None. Example leave(0); // Exit the program Page 50 GAP Communications GAPCDR lputc, lputs ----------------------------------------------------------------- Purpose To display a character or string of characters on the local screen. void lputc(char ch); ch Character to display void lputs(char *str); str String to display Type Low Level Description Like gapputc and gapputs, these functions display either a single character or a string of characters, however the characters are not simultaneously sent to the communications port as well. These functions override the color mode of the caller and allow you to send ANSI color to the local screen even if the caller does not have his color flag turned on. Return Value None. Example lputs("This is a string"); // Send string more ----------------------------------------------------------------- Purpose Checks for a full screen and issues a More Prompt. void more(void); Type High Level Description This is an internal routine that is called by the character output functions. It issues a more prompt if the number of lines displayed reaches the user's page length. Return Value None. Page 51 GAP Communications GAPCDR nl ----------------------------------------------------------------- Purpose Sends a Carriage Return and Line Feed to local and remote. void nl(short lines); lines Number of New Lines to send Type High Level Description To send a blank line, call this routine with the number of blank lines you wish to send. Return Value None Example nl(2); // send two blank lines no_carrier ----------------------------------------------------------------- Purpose Used by the Communications routines. void no_carrier(void); Type High Level Description Internal routine that is called when there is a loss of carrier. Displays a message to the local screen and then calls leave to terminate the program. This function must not be removed from GAPCDR. You may modify it to change the default actions that are taken, but the communications routines must have access to it if there is a loss of carrier. Return Value None. Example Page 52 GAP Communications GAPCDR pagesysop ----------------------------------------------------------------- Purpose Alerts sysop that user wants to chat. void pagesysop(void); Type High Level Description Allows the programer to provide the user with a Page Sysop command. The page lasts for 30 seconds and can be aborted by typing CTRL-K. If the sysop's page bell is on, the sysop's speaker will also sound. To answer the page, the sysop should press CTRL-F10. Return Value None. Example pagesysop(); // tell sysop empty(response,1); // initialize string get_string(response); // get a response if (response[0] == 'P') // wants to chat pagesysop(); // tell sysop pause ----------------------------------------------------------------- Purpose Sends a "Press [Any Key] To Continue" prompt. void pause(void); Type High Level Description This function sends a pause prompt and waits for a key press. Return Value None. Example pause(); // display pause prompt Page 53 GAP Communications GAPCDR putkey ----------------------------------------------------------------- Purpose Used by chat routines to keep track of word wrapping. void putkey(short ch); ch Character to send Type High Level Description This is the main output routine for the chat functions. It keeps track of the current column, and decides when it is time to wrap a word. Return Value None. Example Page 54 GAP Communications GAPCDR read_cnf ----------------------------------------------------------------- Purpose Reads the door configuration file. FILE *read_cnf(char *path); path Full path and name of configuration file Type High Level Description Opens the configuration file for the current door. Normally the passed parameter is the name of the door with a .CNF extension (it is assumed that the file is in the same directory as the door program). If an error occurs, the program ends immediately. WARNING : The first four lines of this configura- tion file belong to the GAPCDR interface module. You are free to use the information, but the in- formation contained in the first four lines must conform exactly to the following specifications. The first line of this file is the full drive and path to the BBS default directory. This is the directory where the BBS created the DOOR.SYS file. The second line is the name of the BBS. The third line is the IRQ for the port, and the fourth line is the Base Address for the port. If the sysop uses Com Ports other than 1 or 2, then he must enter the appropriate IRQ and BASE address so that GAPCDR can properly open the port. If Com ports 1 or 2 are used, then a 0 may be entered on both of these lines. It is the responsibility of the door author to describe the format of these four lines to the end user. If your door program requires no configuration parameters of its own, you can simply distribute a sample configuration file with these four lines already in it. GAPCDR will not close this file after reading the first four lines. It leaves the file open for the programmer's use. Remember that you assign a FILE pointer to the return value so that you may access the file. If your door does require certain configuration parameters, have your users place the Page 55 GAP Communications GAPCDR parameters in the file starting with line 5. If you use a set up program, be sure that your set up program writes the first four lines as specified. After you have called read_cnf and init_door, if you have any configuration options in the configuration file, you should use the stream input routines to read those options. Then fclose the file using the FILE pointer returned. Even if you have no options to read, you must close the file. WARNING : You must call this routine before using any of the GAPCDR functions. After calling this routine, you must call init_door. Return Value FILE pointer. Example FILE *fp; // File pointer fp = read_cnf("TOURIST.CNF"); // read cnf file fclose(fp); // close the file init_door(); // init the door read_doorsys ----------------------------------------------------------------- Purpose Reads the DOOR.SYS universal door interface file. short read_doorsys(void); Type High Level Description Internal routine called by init_door. Reads the DOOR.SYS file and initializes any global variables that depend on the information in that file. Return Value 0 = no error, 1 = error. Example c = read_doorsys(); Page 56 GAP Communications GAPCDR read_gapuser ----------------------------------------------------------------- Purpose Reads the GAP Communications USERS.DAT file. short read_gapuser(char *path); path Full path and name of the USERS file Type High Level Description Reads the user record of the current user in the GAP USERS.DAT file. The record is read into a structure variable called gapuser. You must supply the path and name to the base part of the User file. GAP stores the name of the User file in the GAPBBS.CNF file (which you must read yourself). Read_gapuser will add the .DAT extension. Return Value 0 = no error, 1 = error. Example c = read_gapuser(userpath); read_pcbsys ----------------------------------------------------------------- Purpose Reads the PCBOARD.SYS file. short read_pcbsys(void); Type High Level Description Reads the PCBOARD.SYS system file. The record is read into a structure variable called pcbsys. Return Value 0 = no error, 1 = error. Example c = read_pcbsys(); Page 57 GAP Communications GAPCDR read_pcbuser ----------------------------------------------------------------- Purpose Reads the PCB USERS file. short read_pcbuser(char *path); path Full path and name of the USERS file Type High Level Description Reads the user record of the current user in the PCB USERS file. The record is read into a structure variable called pcbuser. You must supply the path and name to the User file. PCB stores the path\name of the User file in the PCBOARD.DAT file (which you must read yourself). Return Value 0 = no error, 1 = error. Example c = read_pcbuser(userpath); Page 58 GAP Communications GAPCDR read_score ----------------------------------------------------------------- Purpose Reads the score file and displays the results. short read_score(char *datfile,char *message); datfile Path and name of data file to read message Message to display Type High Level Description This function will read the scoreboard data file for your door (if any) and display the results. You pass as parameters the name of the data file to read, and a message to display at the top of the scoreboard. The message could be something like "Top 10 Players". Return Value 0 = scores read, 1 = no scores to read. Example read_score("TOURIST.DAT","Top 10 Tourists"); if (read_score("TOURIST.DAT","Top 10 Tourists")) { nl(1); ansi(BWHITE); show_mess("No one's made it Yet!",NO,YES); } Page 59 GAP Communications GAPCDR reset_port ----------------------------------------------------------------- Purpose Restores the Communications port. void reset_port(void); Type Low Level Description This function must be called prior to exiting the program. It restores the interrupt vector used by the communications routines. It is called internally by leave so it is not necessary for you to explicitly invoke it. Return Value None. Example reset_port(); // Restore communications port Page 60 GAP Communications GAPCDR restore_screen ----------------------------------------------------------------- Purpose Restores a previously saved portion of the screen. void restore_screen(short topr, short topc, short botr, short botc, unsigned short memseg); topr Top row of screen topc Top left column of screen botr Bottom row of screen botc Bottom right column of screen memseg Segment of buffer to save to Type Low Level Description This function allows you to restore a previously saved portion of the screen. You supply the top row and column and the bottom row and column co- ordinates of the rectangle. All co-ordinates are 0 based. The memseg is the segment address of the buffer that a previous call to save_screen saved the video contents to. Return Value None. Example restore_screen(3,8,16,71,dseg); Page 61 GAP Communications GAPCDR rest_cbreak ----------------------------------------------------------------- Purpose Restores the Ctrl-Break vector. void rest_cbreak(void); Type Low Level Description This function must be called prior to exiting the program. It restores the interrupt vector used by the Ctrl-Break routine. It is called internally by leave so it is not necessary for you to explicitly invoke it. Return Value None. Example rest_cbreak(); // restore Ctrl-Break vector rest_int10 ----------------------------------------------------------------- Purpose Restores the interrupt 10 (BIOS) vector. void rest_int10(void); Type Low Level Description When setting up an interrupt 10 BIOS trap to protect a DOS Window, this function must be called when it is no longer necessary to protect a portion of the screen. Return Value None. Example See the example for set_cord. Page 62 GAP Communications GAPCDR rts ----------------------------------------------------------------- Purpose Toggle the RTS line on and off. void rts(short how) how 0 = Turn RTS off. 1 = Turn RTS on Type Low Level Description This routine is used to turn the RTS line of the communications port on or off. Turning RTS off (providing the modem supports hardware handshaking) tells the modem to stop sending data to the computer. It is typically toggled off while writing a buffer of data to a disk. Return Value None. Example rts(0); // Turn RTS off rxempty ----------------------------------------------------------------- Purpose To check if there are any characters in the receive buffer. short rxempty(void); Type Low Level Description This function checks the communications receive buffer to see if there are any characters waiting to be read. Return Value Returns 1 if buffer is empty, 0 if there are characters waiting to be read. Example while (rxempty()) // nothing happening dv_pause(); // give up time slice Page 63 GAP Communications GAPCDR save_screen ----------------------------------------------------------------- Purpose Saves a portion of the screen. void save_screen(short topr, short topc, short botr, short botc, unsigned short memseg); topr Top row of screen topc Top left column of screen botr Bottom row of screen botc Bottom right column of screen memseg Segment of buffer to save to Type Low Level Description This function allows you to save a rectangular portion of the screen. You supply the top row and column and the bottom row and column co-ordinates of the rectangle. All co-ordinates are 0 based. The memseg is the segment address of a buffer to save the video contents to and assumes your buffer was allocated by DOS (i.e., the offset portion of the buffer begins at 0). Return Value None. Example unsigned short dseg; dos_allocatemem(114,&dseg); // get some memory save_screen(3,8,16,71,dseg); // save contents of video Page 64 GAP Communications GAPCDR setport ----------------------------------------------------------------- Purpose Initialize the Communications Port. short set_port(short bufsize, short irq, short base); bufsize Size of Receive buffer irq Port IRQ to use base Port Base Address to use Type Low Level Description This is the port initialization routine that is called by init_com. Bufsize is the size of the receive buffer to set up. Set_port will allocate memory based upon this size. Typical values are from 1200 to 4096 bytes. Note that the bufsize argument is ignored when using the Borland compiler. This is because Borland does not provide a memory allocation routine that allocates memory in the near heap (irregardless of memory model). For Borland, the bufsize is fixed at 2048 bytes. IRQ is the Interrupt Request number to use for the port and Base Address is the address where the port is located. The Port number is a global variable that is set when reading DOOR.SYS. Ports start with 0, where 0 equals COM 1, 1 equals COM 2, etc. For COM 1 and COM 2, you may simply pass 0 as the IRQ and Base address since the defaults for these ports will be used. Return Value 0 = successful, 1 = error encountered. Example // set up the port with a buffer size of 2k, using COM 1 port = 0; if (setport(2048, 0, 0)) exit(1); Page 65 GAP Communications GAPCDR set_attr ----------------------------------------------------------------- Purpose Sets the video color attributes. void set_attr(unsigned char forg, unsigned char back); forg Foreground Color (0-15) back Background Color (0-7) Type Low Level Description This function is used just prior to invoking a DOS Window so that the window colors can be set. Return Value None. Example See the example for set_cord. set_cbreak ----------------------------------------------------------------- Purpose Initializes the Ctrl-Break vector. void set_cbreak(void); Type Low Level Description To trap Ctrl-C and Ctrl-Break, this function should be called to set up an interrupt service routine to trap these two keys. It is imperitive that the program not exit before calling rest_cbreak so that the interrupt vector can be restored. Leave does this for you automatically. Return Value None. Example set_cbreak(); // set up Ctrl-Break ISR Page 66 GAP Communications GAPCDR set_cord ----------------------------------------------------------------- Purpose Set up a DOS Window. void set_cord(unsigned char topr, unsigned char topc, unsigned char botr, unsigned char botc); topr Top left row topc Top left column botr Bottom row botc Bottom right column Type Low Level Description This function sets the window co-ordinates for a DOS Window. Using this function in combination with set_int10 allows you to set up a window into which all local screen output will be directed. Topr and topc are the top left corner of the window and botr and botc are the bottom right corner of the window. All co-ordinates are 0 based. Return Value None. Example _dos_allocmem(114,&dseg); // get some memory save_screen(3,8,16,71,dseg); // save a part of screen set_int10(); // set up BIOS trap set_cord(4,9,15,70); // tell it what to protect set_attr(14,1); // Yellow on Blue cls_all(); // clear the window system("COMMAND"); // go to DOS rest_int10(); // restore vector restore_screen(3,8,16,71,dseg); // restore screen _dos_freemem(dseg); // free memory Page 67 GAP Communications GAPCDR set_int10 ----------------------------------------------------------------- Purpose Set up an interrupt 10 (BIOS) trapper. void set_int10(void); Type Low Level Description This function intercepts the Interrupt 10 vector so that it can trap calls to the BIOS video output routines. It is used in conjunction with set_cord to set up a portion of the screen into which all video output through the BIOS will be directed. If a console driver other than CON or ANSI.SYS is used that writes directly to the screen, this function will not work. Return Value None. Example See the example for set_cord. set_status ----------------------------------------------------------------- Purpose Displays and updates the sysop status line. void set_status(short how); how 0 = set the status line 1 = update the status line 4 = show other user stats Type High Level Description Displays or updates the sysop status line. Return Value None. Example set_status(0); // display status line Page 68 GAP Communications GAPCDR show_file ----------------------------------------------------------------- Purpose Displays a text file. void show_file(char *filename); filename Full path and name of file to display Type High Level Description Many door programs have welcome, news, exit, help and other files to show to the user at various points in the program. This is the function that allows you to do that. To display a file to the user, call the function with the full drive\path\filename of the file to display. If you have color and non-color versions of files pass the name of the non-color version as this function will automatically append a "G" to the filename if the user is in color mode. In fact, this function will always try to find a file with a "G" appended to the end of the name (if the user is in color mode) before it looks for the actual file by the name you specified. If you pass "WELCOMEG" to this function and the user is in color mode, it will first try to find a file with the name of "WELCOMEGG". Pressing CTRL-K or CTRL-X will abort any file display. REMEMBER : If you have both color and non-color versions of the same files, pass the name of the non-color version. Also, the actual disk files must be named in such a way that they have no file extension and the color version ends with a "G". Return Value None. Example show_file("WELCOME"); // display welcome file Page 69 GAP Communications GAPCDR show_mess ----------------------------------------------------------------- Purpose Displays a message. void show_mess(char *message,short bell, short newline); message Message to display. bell YES or NO to ring the bell. newline YES or NO to issue a CR/LF after message. Type High Level Description This is the main string output function for GAPCDR. Under most circumstances, this is the only function that you would call to display output to the user. Return Value None Example show_mess("This is a message!",NO,YES); // the first show_mess displays the string and leaves the // cursor on the same line. The second displays the // string, rings the remote user's bell, and drops the // cursor to the next line. nl(1); show_mess("Are you ready? (Y/N) : ",NO,NO); empty(response,3); get_string(response); if (response[0] == 'Y') // begin whatever it is you want to begin else show_mess("Too Bad!",YES,YES); Page 70 GAP Communications GAPCDR timer ----------------------------------------------------------------- Purpose Pauses for the number of "ticks" specified. void timer(short ticks); ticks Number of timer ticks to pause. Type High Level Description This function allows you to pause all processing for the specified number of ticks. It is in- sensitive to processor speed. The function simply delays the number of "ticks" indicated by the passed parameter. Each tick is 1/18 of a second (or 55 miliseconds). Return Value None. Example timer(18); // pause for 1 second Page 71 GAP Communications GAPCDR time_credit ----------------------------------------------------------------- Purpose Issues timecredits to user. void time_credit(short flag); flag 1 = start timer 0 = end timer Type High Level Description This is basically an internal routine called by chat and sysop shell to DOS so that the user is not penalized for time used. It updates a global variable called timecredit. Timecredit is used in the calculations that determine the user's time remaining. If you wish to use this feature in your own rou- tines, prior to entering your routine, call time_credit with a 1 and it will start the timer. When your routine is finished, call time_credit with a 0 and the timer will stop. The variable timecredit will be updated with the elapsed time. Return Value None. Example time_credit(1); // start the timer time_credit(1); // start the timer do_chat(); // chat with user time_credit(0); // stop the timer Page 72 GAP Communications GAPCDR time_left ----------------------------------------------------------------- Purpose To compute the user's time remaining. void time_left(void); Type High Level Description This is the function that is called by the input and output routines to compute the user's time remaining. It is not necessary for the programmer to call this routine directly. A global variable called timeleft will be updated with each call. This variable may be used in prompts that display the user's remaining time. As long as all input/output is performed thru calls to the GAPCDR library, the timeleft variable will always be current. Return Value None. Example time_left(); // calculate time remaining trim ----------------------------------------------------------------- Purpose Trims spaces from the end of NULL terminated strings. char *trim(char *string); string String containing trailing spaces Type High Level Description This function will remove any spaces from the end of a string. It modifies the passed string. Return Value Pointer to the string without the spaces. Example trim(username); // get rid of spaces Page 73 GAP Communications GAPCDR update_clock ----------------------------------------------------------------- Purpose Updates the status line clock. void update_clock(void); Type High Level Description Internal routine to update the status line clock. Return Value None. Example wrap_word ----------------------------------------------------------------- Purpose To wrap a word during sysop chats. void wrap_word(void); Type Low Level Description Internal function called by putkey to wrap words. Return Value None. Example Page 74 GAP Communications GAPCDR write_gapuser ----------------------------------------------------------------- Purpose Updates the user record in GAP's USERS.DAT file. short write_gapuser(char *path); path Full path and name of Users File Type High Level Description This function allows you to update any variables in the GAP USERS.DAT file for the current user. You must first read the user record before you can write to it. You must pass the path and name of the Users file. The name is obtained by reading GAPBBS.CNF. Write_gapuser will add the .DAT extension. WARNING : The GAP USERS.DAT file contains strings that are fully padded with spaces. If you modify any of these strings, you MUST make sure that the string is fully padded with spaces and that the NULL character is placed in the last string posi- tion. WARNING : The indexes for the user file consists of the user's last name and first name, user's level, and user's handle. Do not under any circumstances modify either of these four fields. Doing so will cause corruption of the Index file. Return Value 0 = no error, 1 = error. Example c = write_gapuser(userpath); // allow user to change city and state c = read_gapuser(userpath); if (c == 0) { show_mess("Enter City/State : ",NO,NO); empty(city,29); // clear string get_string(city); // get response Page 75 GAP Communications GAPCDR if (city[0] != 0) // if something entered { strcpy(user.city,city); // copy it pad(user.city,29); // pad it with spaces c = write_gapuser(userpath); // update user record if (c == 0) show_mess("Saved new City",NO,YES); } } write_pcbsys ----------------------------------------------------------------- Purpose Updates the PCBOARD.SYS file. short write_pcbsys(void); Type High Level Description This function allows the programmer to update the PCBOARD.SYS File. You must first read the file before you write to it and you should not use this function unless you know that your program is running with PCB as the host system. Return Value 0 = no error, 1 = error. Example c = write_pcbsys() // write the file Page 76 GAP Communications GAPCDR write_pcbuser ----------------------------------------------------------------- Purpose Updates the PCB USERS file. short write_pcbuser(char *path); path Full path and name to the Users file Type High Level Description This function allows the programmer to update the PCB USERS File. Do not use unless you know your program is running under a PCB host system. You must first read the user record before you can write to it. You must pass the path and name of the Users file. The name is obtained by reading PCBOARD.DAT. Return Value 0 = no error, 1 = error. Example c = write_pcbuser(); // write the file Page 77 GAP Communications GAPCDR write_score ----------------------------------------------------------------- Purpose Creates and maintains a scoreboard. void write_score(char *filename,long score); filename Path and name of data file to write to score Score to write Type High Level Description This function will create and maintain a scoreboard of the top ten players. You pass it two parameters. The first is a string containing the name of the data file to create/maintain. The second is a long unsigned integer containing the score to write. The user's name and the current date are already known. If the sysop is in the door at the time, the function will simply return and not write a score. The scores will automatically be sorted in decreasing order by the highest score. If you wish to use this routine but your points are kept as shorts instead of longs, simply cast the second parameter to an unsigned long. Return Value None. Example short points; points = 1000; write_score("TOURIST.DAT,(unsigned long) points); Page 78 GAP Communications GAPCDR Index Access1 25, 27 Alarm 21 Ansi 25, 27 Ansi driver color 7, 41, 43, 51 external 15, 18 initializing 10, 48 internal 7, 11, 41 ANSI variables 8, 20 Anystring 24 Backspace 24, 25, 28 Base address 9, 14, 23, 55, 65 Base_add 23, 55, 65 Batch file 14 Baud 16, 17, 18, 21, 49 Baud rate 6, 16, 17, 18, 21, 49, 65 BBS default directory 24, 55 name 24 system files 13, 24, 57, 58, 75, 76, 77 Bbs_dir 24, 55 Bell 21, 70 Birthday 24 Board_name 24 Bphone 22 BS 24 Business phone number 22 Caller alarm 21 Caller's birth date 24 Carriage return 24 Carrier 16, 17, 50, 52 Characters sending to com port 25, 32 sending to local & remote 25, 42 sending to local screen 25, 51 Chat 15, 23, 35, 54 Chatting with user 23 City 22 Ckeypress 25, 28 Clear_scrn 25, 29 Clockon 23, 74 Clr_buf 25, 29 Cls 25, 29, 30 Cls_all 25, 30 Color 7, 18, 21, 23, 27, 41, 43, 45, 51, 66 Page 79 GAP Communications GAPCDR Column 23 Comgetc 18, 25, 31 Comgetd 18, 25, 31 Communications advanced applications 16 base address 9, 14, 23, 55, 65 baud rates 6, 16, 17, 18, 21, 65 carrier 16, 17, 50, 52 configuration file 9 DTR 18 FIFO buffers 6 Functions clr_buf 25, 29 comgetc 25, 31 comgetd 25, 31 computb 25, 32 computc 25, 32 computs 25, 33 dtr 25, 36 init_port 17, 18, 25, 49 iscd 25, 50 no_carrier 25, 52 reset_port 17, 26, 60 rts 26, 63 rxempty 26, 63 setport 17, 26, 65 initializing 17, 48, 49, 65 input 18, 31, 63 interrupt 10, 17, 50, 60 IRQ 9, 14, 23, 55, 65 output 18, 32, 33 port 10, 11, 16, 21, 55, 65 Compilers compiling & linking 11 cputs 11 floating point 8, 12, 46 function calling 12 goto 12 header files 8, 45 printf 11 Quick C 12 supported 8 Compiling 11 Computb 25, 32 Computc 18, 25, 32 Computs 18, 25, 33 Configuration file 9, 10, 14, 55 format 9, 14 Page 80 GAP Communications GAPCDR Control characters 8 editor 8 Cputs 11 CRLF 24, 43 Ctrl-Break handler 10, 62, 66 Curbytes 22 Curfiles 21 Current display color 23 Current download bytes 22 Current files downloaded 21 Current time 23 Cursoff 25, 33 Curson 25, 34 Cursor 25, 33, 34 Curtime 24 Date user's subscription expires 22 Default color 21 Delaying 71 DESQview 16, 17, 25, 28, 31, 37, 38, 39 Dflt_color 21 Display clock 23 Display color 23 Distribution files 7 Do_chat 25, 35 DOOR.SYS 7, 9, 11, 13, 24, 56 Universal format 7 Variables 21 Doors 14 Doors opened 22 Doors_opened 22 DOS shell 15, 18 DOS Window 18, 45, 61, 62, 64, 66, 67, 68 Downbytes 22 Download bytes 22 Downloads 22 DSZ 18 DTR 18, 25, 36 Dv_here 16, 25, 37 Dv_pause 16, 25, 28, 38, 39 Editor 8 control characters 8 Elap_time 25, 39 Empty 25, 40, 47 Endview 23 Event_time 22 Expert 21 Files checking for existence of 25, 27 Page 81 GAP Communications GAPCDR configuration 9, 14 displaying 23, 69 DOOR.SYS 7, 9, 13 GAPCDR.H 8, 10 GAPSTRUC.H 8 PCBOARD.SYS 13 First name 22 Fix_color 25, 41 Flag 23 Floating point 8, 12, 46 Fname 22 Full name 22 Function calling 12 Function keys 15 Functions access1 25, 27 ansi 27 backspace 28 ckeypress 28 clear_scrn 29 clr_buf 29 cls 29, 30 cls_all 30 comgetc 18, 31 comgetd 18, 31 computb 32 computc 18, 32 computs 18, 33 cursoff 33 curson 34 do_chat 35 DOS Window 18 dtr 36 dv_here 16, 37 dv_pause 16, 38 elap_time 39 empty 40, 47 fix_color 41 gapputc 42 gapputs 43 get_attr 18, 45 get_random 46 get_string 40, 47 getakey 44 getkeyc 45 init_ansi 48 init_com 48 init_door 9, 10, 49 Page 82 GAP Communications GAPCDR init_port 17, 18, 49 iscd 50 leave 10, 50 lputc 51 lputs 51 more 51 nl 52 no_carrier 16, 52 pagesysop 53 pause 53 putkey 54 read_cnf 9, 10, 55 read_doorsys 56 read_gapuser 11, 57 read_pcbsys 11, 57 read_pcbuser 58 read_score 59 reset_port 17, 60 rest_cbreak 62 rest_int10 62 restore_screen 61 rts 63 rxempty 63 save_screen 64 set_attr 66 set_cbreak 66 set_cord 67 set_int10 68 set_port 17 set_status 68 setport 65 show_file 69 show_mess 43, 70 time_credit 72 time_left 73 timer 16, 71 trim 73 update_clock 74 wrap_word 74 write_gapuser 75 write_pcbsys 76 write_pcbuser 77 write_score 78 GAPCDR.H 10 Gapputc 25, 42 Gapputs 25, 43 GAPSTRUC.H 8, 45 Gendir 24 Page 83 GAP Communications GAPCDR Get_attr 18, 25, 45 Get_random 25, 46 Get_string 25, 40, 47 Getakey 25, 44 Getkeyc 25, 45 Gotdv 16 Goto 12 Handle 22 Header files GAPCDR.H 8, 10 GAPSTRUC.H 8, 45 Home phone number 22 Hphone 22 Init_ansi 25, 48 Init_com 25, 48 Init_door 9, 10, 25, 49 Init_port 17, 18, 25, 49 Initializing ANSI driver 10, 41, 48 interrupt handlers 10, 65 program 10, 45, 48, 49, 55, 56, 65, 66 strings 25, 40, 47 Input from com port 18, 25, 31, 63 from local & remote 25, 28, 38, 44, 47 from local keyboard 25, 45 Instatus 23 Interrupt handlers BIOS 62, 68 communications 17, 50, 60 CTRL-Break 10, 50, 62, 66 IRQ 9, 14, 23, 55, 65 Iscd 25, 50 Keyboard 28, 38, 44, 45, 47 timeout 28, 47 Last date user was on 22 Last name 22 Last new files scan 22 Last_new 22 Lastdate 22 Leave 10, 25, 50 Level 21 Line feed 24 Lines 23, 51, 52 Linking 11 Lname 22 Local 16, 21 Functions Page 84 GAP Communications GAPCDR cls 25, 30 cls_all 25, 30 cursoff 25, 33 curson 25, 34 getkeyc 25, 45 lputc 25, 51 lputs 25, 51 Local mode 11, 16 Lowercase characters 23, 47 Lputc 25, 51 Lputs 25, 51 Maindir 24 Make_sound 25 Maxbytes 22 Maxfiles 21 Maximum bytes available 22 Maximum files available 21 Mesleft 22 Messages left 22 Minsleft 21 Minutes left at door start 21 More prompt 23, 25, 51 Multi 11, 21 Multi user 11, 15, 27 Name of the BBS 24 NL 25, 52, 70 No clock 23 No_carrier 16, 17, 25, 52 Node 21 Node number 21 Non Stop mode 23 Normal 23 Noup 23, 47 Novice 21 NS 23, 51 Number of downloads 22 Number of times on 22 Output to com port 18, 25, 32, 33 to local & remote 25, 26, 42, 43, 70 to local screen 25, 51 Page 21 Page bell 15, 21, 53 Page length 21, 51 Pagesysop 25, 53 Parity 21 Pascal function calling 12 Page 85 GAP Communications GAPCDR Password 22 Path to DOOR.SYS 24 Pause 25, 53 Pausing 71 PCBOARD.SYS 13 PKUNZIP 18 Port 16, 17, 21, 55, 65 Printer 21 Printf 11 Prompts more 51 pause 53 Putkey 25, 54 Quick C 12 Random number generator 10, 25, 46 Read_cnf 9, 10, 25, 55 Read_doorsys 26, 56 Read_gapuser 11, 26, 57 Read_pcbsys 11, 26, 57 Read_pcbuser 26, 58 Read_score 26, 59 Realcredit 21 Receive buffer 28, 29, 31, 63, 65 Recnum 22 Redisplay 23 Remote user 21 Remote user's bps rate 21 Reset_port 17, 26, 60 Rest_cbreak 26, 62 Rest_int10 26, 62 Restore_screen 26, 61 Rts 26, 63 Rxempty 26, 63 Save_screen 26, 64 Scan codes 45 Scoreboard 59, 78 Screen 21, 61, 64 clearing 29, 30 color 45, 51, 66 cursor 33, 34 full 51 Set_attr 26, 66 Set_cbreak 26, 66 Set_cord 26, 67 Set_int10 26, 68 Set_status 26, 68 Setport 17, 26, 65 Shell to DOS 15 Page 86 GAP Communications GAPCDR Show_file 26, 69 Show_mess 26, 43, 70 Single user 11, 21 Starttime 23 Status line displaying 15, 23, 68 protected 15 Strings initializing 25, 40, 47 receiving from local & remote 25, 40, 47 removing spaces from 73 sending to com port 25, 33 sending to local & remote 25, 43, 70 sending to local screen 25, 51 Strtime 24 Structures 24 Subscrip 22 Sysname 24 Sysop batch file 14 function keys 15 functions 13, 15 setup 13 Sysop's name 24 System files 13, 57, 58, 75, 76, 77 Temptime 23 Time 23 Time credits 21, 72 Time door opened 23 Time slice 16, 28, 31, 37, 38, 39 Time user has left 23, 39, 44, 73 Time_credit 26, 72 Time_left 26, 73 Timecredit 13, 23 Timeleft 23, 28, 44, 73 Timenow 23 Timeout 28 Timer 16, 26, 71 Timeson 22 Total uploads 22 Trim 26, 73 Twit 15 Upbytes 22 Update_clock 26, 74 Updating status line 23 Upload bytes 22 Uploads 22 Uppercase characters 23, 47 Page 87 GAP Communications GAPCDR Usemore1 23 User Record 24 User's birth date 24 User's business phone 22 User's first name 22 User's full name 22 User's Handle 22 User's home phone 22 User's home town 22 User's last name 22 User's password 22 User's record number 22 User's security level 21 Userbaud 21 Username 22 Variables ANSI 8, 20 Defines NO 20 YES 20 DOOR.SYS alarm 21 baud 16, 21 bell 21 bphone 22 city 22 color 21 curbytes 22 curfiles 21 dflt_color 21 doors_open 22 downbytes 22 downloads 22 event_time 22 expert 21 fname 22 handle 22 hphone 22 last_new 22 lastdate 22 level 21 lname 22 local 16, 21 maxbytes 22 maxfiles 21 mesleft 22 minsleft 21 multi 11, 21 Page 88 GAP Communications GAPCDR node 21 page 21 parity 21 password 22 port 16, 17, 21 printer 21 realcredit 21 recnum 22 screen 21 subscrip 22 timeson 22 upbytes 22 uploads 22 userbaud 21 username 22 Global anystring 24 base_add 23 bbs_dir 24 birthday 24 board_name 24 BS 24 chat 23 clockon 23 column 23 CRLF 24, 43 curtime 24 endview 23 flag 23 gendir 24 gotdv 16 instatus 23 IRQ 23 lines 23 maindir 24 normal 23 noup 23, 47 NS 23 redisplay 23 starttime 23 strtime 24 sysname 24 temptime 23 timecredit 13, 23 timeleft 23 timenow 23 usemore1 23 view 23 Page 89 GAP Communications GAPCDR wordwrap 23 Structures pcbsys 24 pcbuser 24 user 24 View 23 Window 18, 61, 62, 64, 66, 67, 68 Wordwrap 23, 54, 74 Wrap_word 26, 74 Write_gapuser 26, 75 Write_pcbsys 26, 76 Write_pcbuser 26, 77 Write_score 26, 78 Page 90